CIBasic

The CIBasic component provides common interfaces used by all plug-ins.

Acquiring the CIBasic component

To use the CIBasic component, you must first acquire it using the CIInterfaceManager interface passed to your plug-in as part of the PMMessage structure.

PMXErr main(PMMessage *pMsg)
{
    CIInterfaceManager * pIntfMgr = pMsg->pInterfaceMgr;
    CIBasic     * pBasic;
    pIntfMgr->AcquirePMInterface(PMIID_BASIC,(void **) &pBasic);
    ...

When you have finished using the CIBasic component, you must release it:

    pIntrMgr->ReleasePMInterface((void **) pBasic);

Summary

The CIBasic interface contains 38 interfaces, in six categories:

Memory management Coordinate conversion

PlugInLib Point conversion

PM Events Windows specific

CIBasic Interfaces

DCtoWC GetDCOrg GetParm

GetPlugInLibProperty GetPMInst GetPMResInst

GetRulerOrg LockData LockData

LWCtoXDC LWCtoYDC LWUtoLXDU

LWUtoLYDU LWUtoXDU LWUtoYDU

LXDUtoLWU LYDUtoLWU PMInterfaceVersion

PMMemAlloc PMMemFree PMMemRealloc

RegisterPMEvent SetDCOrg SetPlugInLibProperty

Unlock UnregisterPMEvent WCtoDC

WCtoXDC WCtoYDC WUtoDU

WUtoXDU WUtoYDU XDCtoLWC

XDCtoWC XDUtoWU YDCtoLWC

YDCtoWC YDUtoWU

CIBasic Interfaces
DCtoWC	GetDCOrg	GetParm
GetPlugInLibProperty	GetPMInst	GetPMResInst
GetRulerOrg	LockData	LockData
LWCtoXDC	LWCtoYDC	LWUtoLXDU
LWUtoLYDU	LWUtoXDU	LWUtoYDU
LXDUtoLWU	LYDUtoLWU	PMInterfaceVersion
PMMemAlloc	PMMemFree	PMMemRealloc
RegisterPMEvent	SetDCOrg	SetPlugInLibProperty
Unlock	UnregisterPMEvent	WCtoDC
WCtoXDC	WCtoYDC	WUtoDU
WUtoXDU	WUtoYDU	XDCtoLWC
XDCtoWC	XDUtoWU	YDCtoLWC
YDCtoWC	YDUtoWU

The Memory Management interfaces

void *PMMemAlloc(unsigned long blockSize);

Use the PMMemAlloc interface to allocate memory in your plug-in. You should use this interface rather than general C/C++ functions (malloc/new) or operating systems functions (NewHandle). This way, memory usage is coordinated with PageMaker, and low memory situations can be handled by PageMaker effectively.

Make sure to check that the returned pointer is not null before using it.

void PMMemFree(void * memBlock);

Use PMMemFree to free memory allocated with PMMemAlloc.

void *PMMemRealloc(void * memBlock, unsigned long newSize);

Use PMMemRealloc to change the size of a memory block that was allocated with PMMemAlloc. Make sure to check that the returned pointer is not null before using it.

The PlugInLib interfaces

PMXErr SetPlugInLibProperty(unsigned long theProperty);

Modify the property settings for the plug-in. These properties are originally defined in the ADNI resource, but can be changed at runtime.

kStayInMem Keep this plug-in in memory

kLibRegister Causes the application to call the plug-in at start up, so that the plug-in can register for event notification and publish custom interfaces. Changing the kLibRegister bit in the plug-in at run-time will have no affect, but the attribute is included here for completeness.

kDisablePMEvent The plug-in will not receive any PageMaker event notifications.

kDisablePMSysEvent The plug-in will not receive any system event notifications.

kDisableNonCQEvent The plug-in will only receive command and query (.

unsigned long GetPlugInLibProperty();

Retrieve the property settings for the plug-in. These properties are originally defined in the ADNI resource, but can be changed at runtime using these interfaces. The bit values returned are the same as described above for SetPlugInLibProperty.

unsigned short PMInterfaceVersion();

This interface returns the version of the PageMaker Plug-in interface supported by the application. For PageMaker 6.5, this should be 3.

The PM Event interfaces

To support event notification, the RegisterPMEvent and UnregisterPMEvent interfaces let the Plug-in dynamically register and unregister for the PageMaker Events.

PMXErr RegisterPMEvent(PMEventID eventID);

Registers the plug-in to receive notification when the event specified by PMEventID occurs. The PMEventID values are defined in PMEvent.h

PMXErr UnregisterPMEvent(PMEventID eventID);

Removes the plug-in's registration for the event specified in PMEventID. The plug-in will no longer be notified when that event occurs, but all other events remain unchanged.The PMEventID values are defined in PMEvent.h

char *LockData(void * ParamData, int ParamNumber=0);

Locks the parameter indicated by ParamNumber so that it can be retrieved by GetParm(). LockData returns a pointer that must be cast to the data type of the parameter in the buffer. The pointer that is returned is a pointer to the parameter.

PMXErr LockData(void * ParamData, void * pBuffer, int BuffSize);

Locks a buffer so that the information can be retrieved.

void Unlock(void * ParamData, int ParamNumber=0);

Unlocks the parameter specified by ParamNumber.

PMXErr GetParm(void * ParamData, int ParamNumber, int DataType, void * pBuffer);

This interface extracts information from a PMEVT_PLUGIN_COMMAND record. The plug-in must know the format of the data passed, opies the specified parameter into a buffer.

You should bracket calls to GetParm with LockData and Unlock.

The PMEVT_PLUGIN_COMMAND record is supplied by the PMEVT_PLUGIN_COMMAND_BEFORE and PMEVT_PLUGIN_COMMAND after events.

The eDataType enumeration is used by the GetParm() interface to indicate the type of data held in the buffer. These is defined in CIBasic.h.

PMXTShort PMXTHandle PMXTLong PMXTByte PMXTText PMXTBool

The Coordinate conversion interfaces

PMXErr SetDCOrg(DCPOINT *pNewPubDC, DCPOINT *pOldPubDC);

Moves the publications origin to the location pNewPubDC. The location of the old origin is returned, relative to the new origin, in pOldPubDC.

Warning: If your plug-in changes the origin, you must return the origin to its original location before returning control to the PageMaker application.

The PageMaker publication cooridante system has its origin in the center of the pasteboard. Positive x values are to the right of the origin and positive y values are below the origin (towards the bottom of the pasteboard.)

PMXErr GetDCOrg(DCPOINT *outPubDC, DCPOINT *outScreenDC);

Returns the offset of the upper right hand corner of the screen to the center of the publications pasteboard.

pPubDC is the location of the upper right hand corner of the screen, in the publication's coordinate system.

pScreenDC is the location of the center of the pasteboard, in the screen coordinate system.

The interface returns CQ_INVALID_STATE is returned if there is no open publication.

PMXErr GetRulerOrg(LONGPOINT *pRulerOrg);

Returns the location of the ruler zero point pRulerOrg, the value returned is in twips The location is given in relation to the publications origin which is at the center of the pasteboard.

DC WCtoXDC(WC xwc);

Converts the x value of a point in the world (publication) coordinate system to its current value in the screen coordinate system.

Note: WUtoXDU() is similar to WCtoXDC() but WCtoXDC() converts locations, while WUtoXDU is for unit conversion.

If the publications origin has been moved, then you must use LWCtoXDC() to prevent overflow errors.

DC WCtoYDC(WC ywc);

Converts the y value of a point in the world (publication) coordinate system to its current value in the screen coordinate system.

Note: WUtoYDU() is similar to WCtoYDC() but WCtoYDC() converts LWCtoYDClocations, while WUtoYDU is for unit conversion.

If the publications origin has been moved, then you must use LWCtoYDC() to prevent overflow errors.

DC LWCtoYDC(long lwc);

Converts the y value of a location in the world coordinate system, lwc, and returns the value for same location in the screen coordinate system.

Note: LWCtoYDC converts the y value of a location. The value returned is dependent on both the current zoom state and the offset between the screen and world coordinate systems. If the origin of the world coordinate system is in its original location, the center of the pasteboard, WCtoXCDC() can be used.

WC XDCtoWC(DC xdc);

Converts the x value of a point on the screen xdc to the location it currently represents in the world coordinate system.

Note: XDCtoWC converts the x value of a location. The value returned is dependant on both current zoom state, and the offset between the screen and world coordinate systems. If the orgin of the world coordinate system has been moved, use XDCtoLWC() to prevent overflow errors.

WC YDCtoWC(DC ydc);

Converts the y value of a point on the screen ydc to the location it currently represents in the world coordinate system.

Note: YDCtoWC converts the y value of a location. The value returned is dependent on both current zoom state, and the offset between the screen and world coordinate systems. If the orgin of the world coordinate system has been moved, use YDCtoLWC() to prevent overflow errors.

DC LWCtoXDC(long lwc);

Converts the x value of a location in the world coordinate system, lwc, and returns the value for same location in the screen coordinate system.

Note: LWCtoXDC converts the x value of a location. The value returned is dependant on both the current zoom state and the offset between the screen and world coordinate systems. If the origin of the world coordinate system is in its original location, the center of the pasteboard, WCtoXDC() can be used.

long XDCtoLWC(DC xdc);

Converts the x value of a location in the screen coordinate system, xdc, to the location it currently represents in the world coordinate system and returns it as a long. The value returned is dependant on both the current zoom state and the offset between the screen and world coordinate systems. If the origin of the world coordinate system is in its original location, the center of the pasteboard, XDCtoWC() can be used.

long YDCtoLWC(DC ydc);

Converts the y value of a location in the screen coordinate system, ydc, to the location it currently represents in the world coordinate system and returns it as a long.

Note: This method coverts the y coordinate of a location. The value returned is dependant on both the current zoom state and the offset between the screen and world coordinate systems. If the origin of the world coordinate system is in its original location, the center of the pasteboard, YDCtoWC() can be used.

DC WUtoXDU(WC wu);

Converts the x value, wu, in the world coordinate system to the length on the screen that would represent that value and returns a short.

Note: This method converts the length only. The return value is dependent only on the current zoom rate, and not on the offset between the screen and world coordinate origins.

DC widthOnScreen; const MAX_SHORT = 0x7FFF; PGetPageSize pgSize; if (pgSize.xWidth !> MAX_SHORT) widthOnScreen = WUtoXDU(pgSize.xWidth);

DC WUtoYDU(WC wu);

Converts the y value, wu, in the world coordinate system to the length on the screen that would represent that value and returns a short.

Note: This method converts the length only. The return value is dependent only on the current zoom rate, and not on the offset between the screen and world coordinate origins.

Example:

DC heightOnScreen; const MAX_SHORT = 0x7FFF; PGetPageSize pgSize; if (pgSize.yHeight !> MAX_SHORT) heightOnScreen = WUtoXDU(pgSize.yHeight);

WC XDUtoWU(DC xdu);

Converts the distance along the x axis in the screen coordinate, xdu, system to the world coordinate system and returns the value as a WC (a short.)

Note: This method converts the measurement only. The return value is dependant on the current zoom rate but not on the offset between the screen and world coordinate origins.

WC YDUtoWU(DC ydu);

Converts the distance along the y axis in the screen coordinate, ydu, system to the world coordinate system and returns the value as a WC (a short.)

Note: This method converts the measurement only. The return value is dependant on the current zoom rate but not on the offset between the screen and world coordinate origins.

long LXDUtoLWU(long xdu);

Converts the x value that represents a length along the x axis in the screen coordinate system, xdu, to the distance that it currently represents in the world coordinate system and returns that value as a long.

Note: This method converts the measurement only. The return value is dependant on the current zoom rate but not on the offset between the screen and world coordinate origins.

long LYDUtoLWU(long ydu);

Converts the y value that represents a length along the x axis in the screen coordinate system, ydu, to the distance that it currently represents in the world coordinate system and returns that value as a long.

Note: This method converts the measurement only. The return value is dependant on the current zoom rate but not on the offset between the screen and world coordinate origins.

The Point conversion interfaces

void WCtoDC(LPWCPOINT pwcpoint, LPDCPOINT pdcpoint);

Converts a point in the world coordinate system, pwcpoint, to the point that represents it in the screen coordinate system. The result is returned in pdcpoint.

Note: The point returned by this method is dependant on the current zoom rate and the offset between the world and screen coordinates, which enables this method to convert locations in the publication to their current location on the screen.

void DCtoWC(LPDCPOINT pdcpoint, LPWCPOINT pwcpoint);

Converts a point in the screen coordinate system, pdcpoint, to the point that it represents in the world coordinate system. The result is returned in pwcpoint.

Note: The point returned by this method is dependant on the current zoom rate and the offset between the world and screen coordinates.

void WUtoDU(LPWCPOINT pwcpoint, LPDCPOINT pdcpoint);

Converts a width and height in the world coordinate system, pwcpoint, to the width and height in the screen coordinate system that would represent those values. The result is returned in pdcpoint.

Note: This method converts the width and height only. The result is dependant on the current zoom state, but not the offset between the world and screen coordinate origins.

DC LWUtoXDU(long wu);

Converts a measurement on the x axis, wu, from the world coordinate system to the screen coordinate system. The measurement is a long value, in twips, and the return is a short representing the screen value.

Note: The result given by this method is dependant on the current zoom rate, but not on the offset between the screen and world coordinate origins.

DC LWUtoYDU(long wu);

Converts a measurement on the y axis, wu, from the world coordinate system to the screen coordinate system. The measurement is a long value, in twips, and the return is a short representing the screen value.

Note: The result given by this method is dependant on the current zoom rate, but not on the offset between the screen and world coordinate origins.

long LWUtoLXDU(long wu);

Converts a measurement on the x axis, wu, from the world coordinate system to the screen coordinate system. The measurement is a long value, in twips, and the return is a long representing the screen value.

Note: The result given by this method is dependant on the current zoom rate, but not on the offset between the screen and world coordinate origins.

long LWUtoLYDU(long wu);

Converts a measurement on the y axis, wu, from the world coordinate system to the screen coordinate system. The measurement is a long value, in twips, and the return is a long representing the screen value.

Note: The result given by this method is dependant on the current zoom rate, but not on the offset between the screen and world coordinate origins.

The Windows specific interfaces

HINSTANCE GetPMInst();

Windows only. This interface is not present on Mac OS, and will cause a compile error.

HINSTANCE GetPMResInst();

Windows only. This interface is not present on Mac OS, and will cause a compile error.

Measurement types

typedef short DC; // screen device coordinates
typedef short WC; // world coordinates

typedef struct __WCPOINT { // a world coordinate point
WC x; WC y; } WCPOINT, DCPOINT, *LPWCPOINT, *LPDCPOINT;

Comments or suggestions? Contact Adobe Developer Support

Memory management	Coordinate conversion
PlugInLib	Point conversion
PM Events	Windows specific

kStayInMem	Keep this plug-in in memory
kLibRegister	Causes the application to call the plug-in at start up, so that the plug-in can register for event notification and publish custom interfaces. Changing the kLibRegister bit in the plug-in at run-time will have no affect, but the attribute is included here for completeness.
kDisablePMEvent	The plug-in will not receive any PageMaker event notifications.
kDisablePMSysEvent	The plug-in will not receive any system event notifications.
kDisableNonCQEvent	The plug-in will only receive command and query (.